Ultimedia 1/Ultimedia 1.iso/tools/soundtools/xmodule/xmodule.doc

Text File | 1994-07-30 | 20.9 KB | 494 lines

   This manual documents XModule version 2.8 released on 28 Jul 94.

   Copyright (C) 1993-1994 by Bernardo Innocenti, Freely distributable,
all rights reserved.

Overview
********

   The Amiga computer has standard file formats for almost everything.
Graphics, text, animation, hypertext and many other data types are
easily imported into any program that supports the given standards.
But this isn't true for music.  Too bad the music interchange file
format defined by Electronic Arts (the old IFF SMUS) was too poor to be
usable in high-quality music sequencers.  Therefore, every music editor
created its own proprietary module format, so that, for instance, you
cannot load into ProTracker music written with Oktalyzer.

       XModule (pronounced Cross Module) born as music module
conversion utility that tries to solve this problem.  The project
started in early 1993, as a friend of mine (Fabio), who wrote a lot of
(good) music on Oktalyzer, needed ProTracker to obtain certain effects.
He had an old PD conversion program called Tracker that worked only
in particular conditions and was really bogus.  So I decided to contact
the author and he let me have the source for Lit30000  (about $20).

   The original program has been completely rewritten from scratch, as
the source was really poorly coded.  At the moment, Oktalyzer,
ProTracker, NoiseTracker and SoundTracker are the only supported
formats, but I'm still developing XModule, so contact me if you want to
see your favorite music editor added to this (short) list (see Author
Info).

   Now XModule sports many other features, like module optimization, a
nice user interface and complex module editing.  This is why I like to
call XModule a module processor.  XModule is to the music processing
what ADPro and ImageFX are to image processing (am I a bit immodest?
:-).

Distribution
************

   XModule is a Freeware program.  This means that you (probably)
have got it free and you should not ask any money if you decide to
copy it for someone else.  If, instead, someone sold you XModule for a
price higher than the media used to store it on (i.e. $1 for a DD
disk), tell him he should try making money honestly.

   I'm not asking you to pay for XModule because I never paid for a
ShareWare program, so I felt that I somehow had to pay my debt and I
decided to distribute XModule as free software, a little gift to all
the Amiga community.  Feel free to distribute XModule to your friends
and enemies, but, if you do so, you must keep the documentation and
the other distribution files together with the executable.  The source
code is not required, but I'm distributing it to let others take
advantage of my work, so, if possible, try to include the source too.

   Fred Fish, SAN, ADS and Aminet are especially granted permission to
include XModule into their PD libraries.  Other PD libraries are
welcome as well.

   If you intend to include XModule or parts of it in a commercial
package, please at least send me a free copy of the product.  I would
be honored to see one of my programs being part of a commercial package.

   You can modify or improve XModule (see Programmers), only be so kind
to return the new source code to me, so I can put the new features in
the next release.  And, please, do not strip my name from the
documentation, the program source, or the executable.

   This product is provided as is, without warranties of any kind:
the author of this program cannot be held liable for any defects in the
executable nor in the documentation or in any other files contained in
this package.  Any damage directly or indirectly caused by the
use/misuse of XModule is the sole responsibility of the user her/him
self.  In other words: XModule never formatted my hard disk nor killed
my dog, so I suppose it won't cause any damage to your system either,
but, just in case, do not blame me if something nasty happens.

Getting Started
***************

   XModule requires KickStart version 2.0 or greater.  The reason is
that I hate programming on 1.3 and I won't do it any more.  If you still
haven't upgraded to 2.0, you'll miss the chance to run XModule and many
other wonderful programs.  So what are you waiting for?

   XModule also takes advantage of some 3.0 features, like DataTypes,
AmiGaGuide, Locale and some enhancements for the user interface.

   You can invoke XModule either from the Shell or Workbench.  XModule
accepts both command line and ToolTypes arguments.  Workbench and Shell
parameters are the same.  The full AmigaDOS template is:

     XModule FROM/M,PUBSCREEN/K,PORTNAME/K

The FROM keyword specifies optional modules to load at startup time.
From Workbench, you multi-select module icons instead of specifying a
ToolType.

   Specifying the PUBSCREEN keyword, followed by a public screen name,
allows you to open XModule on an existing public screen.  The given
name should match exactly (case matters), or the system won't be able to
find the requested screen.  If the screen does not exist, a new public
screen will open, cloning Workbench resolution and palette.  Note that
this behavior is not standard: Commodore commodities will abort if the
required public screen does not exist.  The default for this option is
"Workbench", that will open XModule on the Workbench screen.

       PORTNAME will change the name of XModule's ARexx port.  If a
port with this name already exists, a number (eg: ".1") will be
appended to the name, until a unique name is found.  The port name
defaults to "XMODULE".  For more about the ARexx port, consult the
ARexx Interface chapter.

User Interface
**************

   XModule's GUI follows Commodore's 2.0 style guidelines.  Under
Kickstart 3.0 and above, XModule takes advantage of some new OS
capabilities to enhance some aspects of the GUI.

   Gadget layout is font sensitive, but using some fancy fonts could
give you a strange user interface look.  If you are using a very big
font and a window becomes too big to fit in the screen, topaz/8 will
be used as a fallback for rendering that window.  When you close a
window, it will remember its position and size when you open it again.
The same applies to window zooming.

   In all windows, the following shortcut keys are active:

ESC
     Close the active window.  Does not work with ToolBox window, as it
     would make it too easy to accidentally exit the program.

HELP
     Bring up AmigaGuide on-line help.  This feature requires
     amigaguide.library, which is part of Workbench 2.1 and up,
     and XModule.guide located in the current directory or in the
     same directory of XModule's executable or in HELP:language/
     directory, where language is one of your Locale preferred
     languages.

TAB
     Cycle forward through string and numeric gadgets within the active
     window.  SHIFT-TAB will cycle backwards.  TAB also activates
     the first string or numeric gadget if none is selected.

Cursor up/down
     Move up and down in a viewlist whenever the active window contains
     one.  SHIFT-Cursor moves 5 items up/down. ALT-Cursor moves to
     the top or to the bottom of the list.

   In addition, gadgets with underscored characters in labels, can be
selected hitting the highlighted key.  SHIFT-key acts the opposite of
the unshifted key (sliders are decremented by one, cycle gadgets will
cycle backwards, etc).

Panels
******

   Sorry, XModule's documentation is still incomplete.  The next release
will hopefully be more accurate.

   But wait! Do not commit suicide for such a reason: XModule is very
easy to use, and you will be able to operate it even without this
chapter.

ToolBox Window
==============

   Gadgets:

   Project Menu:

Format Conversion
*****************

   XModule can load and save modules created by other music editors.
The following is a list of supported module formats:

* NoiseTracker
     Noise/ProTracker 31 instruments module.  This is the default.

* ProTracker 2.3
     ProTracker 2.3 new 100 patterns module.  XModule will automatically
     switch to ProTracker 100 whenever the converted module exceeds
     the 64 patterns limit.

         Warning: You must load such a module with ProTracker 2.3 or
     better in order to play/edit it.  Older players will either refuse
     to load or turn the module into scratch dance.

* SoundTracker 15 instrument module
     This is pretty useless as SoundTracker is becoming quite rare.  Do
     not save SoundTracker modules unless you really need to, because
     most players/editors will stop supporting this format very soon.
     SoundTracker format has no way of identifying a module, therefore
     XModule will ask you to confirm a SoundTracker module when the
     file being loaded matches no other module format.

* UnicTracker
     Actualy I've never seen UnicTracker, but I sometimes ripp Unic
     modules with ExoticRipper, so I decided to give support for this
     weird Tracker clone too.  The format is very similat to
     ProTracker, except for the EMW3 ID.

* Oktalyzer V1.1
     Oktalyzer is an old editor which can play up to 8 channels by
     mixing instruments in real time.

   As a matter of fact, there are things that simply cannot be done
because of the big differences between module formats.  Below is a list
of the internal limitations of each module formats.  When you save to a
particular format, if the module exceeds one of this values, or makes
use of features not implemented, some data will be stripped away to
produce at least a partial conversion.


     Program          Instr  MaxPatt PattLen SongLen InstrLen
     --------------------------------------------------------
     Oktalyzer         36      128     128     128     128K
     Sound Tracker     15       64      64     128      64K
     Noise Tracker     31       64      64     128      64K
     Pro Tracker       31      100      64     128      64K
     MED/OctaMED       63      256     256     256   No Limit

     Where:
     #Instr   is the maximum number of instruments,
     MaxPatt  is the maximum number of patterns,
     PattLen  is the maximum number of lines per pattern,
     SongLen  is the maximum number of positions in a song,
     InstrLen is the maximum size of an instrument given in bytes.

   Effects are the hardest thing to convert.  While Speed and Volume
are almost the same between different music editors, some effects (such
as Oktalyzer's H and L) cannot be converted because there are no
equivalents in other music editors.  Therefore, you will have to modify
the score manually if you intend to convert a module while keeping such
effects.  In addiction, some effects behave in different ways even if
they claim to do the same thing.

   Last but not least, some music editors support synthetic or hybrid
instruments.  Fortunately, none of the module formats known by XModule
implement such instruments, because I can hardly think of a way to
implement a sample to synth conversion (any ideas?).  I used to like
synthetic music, but it seems that all those great composers on the
good old C64 have vanished...  Why have you musicians become so lazy?
8-(

Optimization
************

   Module optimization is achieved by removing all unused data in such
a way that the module will sound the same as before.  XModule can
process a module to reduce its size as much as possible.  It is
generally a good idea to optimize a module before distributing it, but
never while you are still composing it, because you could easly loose
some data that you didn't want to discard.  Do not expect to gain a lot
of bytes optimizing modules: saving 20% of the total size is usually a
very good result.

* Unused patterns
     Some formats (e.g.: Sound/Noise/ProTracker) store empty patterns
     in a module if a pattern with a greater number is used.  For
     instance, a song using patterns 1, 2 and 5 will contain patterns 3
     and 4 as well.

         Warning: If a song contains a part that has not been finished
     yet and has not already been inserted in the position table, you
     will lose it.

         Warning: When a song is saved to Noise/ProTracker, patterns
     beyond the last used patterns are discarded regardless of this
     switch.  This is due to a limitation of Noise/ProTracker module
     format.

* Unused instruments
     A composer may decide to use an instrument and then change his
     mind, but forget to clear the instrument.  In this case the module
     will contain an instrument that is never played.  These instruments
     are simply stripped away.

* Sample data after a loop
     The part of an instrument following a loop is never played and is
     therefore discarded.

* Instruments zero tails
     Long zero tails eat up memory and produce no sound.  This
     optimization is performed only on loopless instruments, as a zero
     sequence inside a loop does make difference.  XModule leaves at
     least two zero bytes to avoid the nasty click produced by the
     speaker dropping its volume to zero too quickly.

ARexx Interface
***************

   Sorry, XModule's documentation is still incomplete.  The next release
will hopefully be more accurate (it's already three releases I'm
promising it :-).

   Anyway, XModule's ARexx port is a little brain dead at the moment,
so you're not missing a great deal.

Known Bugs
**********

   Murphy's laws state that nothing can be perfect, not even computer
programs.  XModule is far from being perfect and I need your help to
fix as many bugs as possible.  If you discover a bug which isn't
reported in the list below (note: there is no list at the moment; this
is a beta release, remember?), please notify me.

   When you report a bug, state exactly what happens and indicate how
to reproduce the conditions that generated the problem.  Reports like
`XModule sometimes crashes converting my favorite module' does not help
at all.  Include your name if you want to be credited in future XModule
releases.

   If the program refuses to convert a module, mail it to me on a disk
or upload it to a BBS that I can reach and I'll try to fix the problem
as soon as possible.  Glass Globe BBS, whose address can be found in
the Author Info chapter, will do.  If you want the disk back with the
fixed version of XModule, send me a self-addressed envelope with enough
italian stamps or enough money for a reply.

   XModule has been tested on several machines running Kickstart 2.0,
3.0 and 3.1.  It should work on any 68K family processor (tested on
68000, 68020 and 68040) and is Enforcer and Mungwall proof.  I also
tested XModule with virtual memory programs (such as VMM40) and found
that everything seems to work correctly.

Future plans
************

* OctaMED
     This will probably be the next format I'll work on.  I think this
     is the best music editor available on the Amiga, but I haven't yet
     got enough infos on its file format to code a conversion routine.
     If you have such information, please contact me (see Author Info).

* TeX
     Another format I would like to add is AmigaTeX.  If you know TeX,
     you will surely be wondering what a typesetting program can be
     used for in music.  Well, AmigaTeX is at the moment is the best
     implementation available on any computer of the TeX typesetting
     program, and its distribution includes MusicTeX, a powerful
     music language which can output notes in a great standard staff
     notation.  I know no other program on the Amiga that can print
     notes of such fine quality (if you do, let me know!), so I think
     that many musicians would appreciate such an option.

* Other module formats
     If you have documentation regarding a format you would like to see
     in a next release, please send it to me together with a couple of
     modules and, if possible and legal, the program that created them.
     I'll try to implement the new format only if it is somewhat easy:
     it is very hard to convert, say, Future Composer to SoundTracker.
     Do not send a module without a text file describing its structure,
     as I'm not willing to spend my nights hex-dumping modules :).

Programmer notes
****************

   XModule has been written in C and compiled with SAS C version 6.51,
Other compilers may require some changes to the source.

   The program is written in respect of the Amiga multitasking
operative system and complies with Commodore programming guidelines.
All allocated resources will be (hopefully) freed before program
termination.  I wrote XModule with the goal in mind of keeping the
executable fast and small.

   This manual has been typeset using MakeInfo, a GNU PD utility ported
to the Amiga by Reinhard Spisser and Sebastiano Vigna.  I found that
the time I saved writing one file for three was nearly compensated by
the time I spent learning how to operate MakeInfo.  As I'm not that
skilled in using TeX and MakeInfo, you will probably find this document
a bit silly in its typesetting style.

   Besides, English is not my first language (as you might have
guessed) and I bet this document is full of grammar mistakes.

   If you intend to translate, improve or somewhat edit this document,
please work on the supplied TexInfo file and then process it with the
utilities supplied in the MakeGuide distribution.  You can find
MakeGuide in several PD libraries such as BBSs.

   Do not hesitate to send criticisms to my work, and, even better,
advices on how to improve the program and the documentation.  See
Author Info.

Credits
*******

   * Fabio Barzagli, for beta testing version 1.x, for the money he
     paid me for it and, last but not least, for letting me have (or
     steal?) his awesome modules!

     Keep on making good music, Fabio!

   * Alessandro Lombardi, for 2.x beta testing.

     Stop deleting files!

   * Massimo Brogioni, for being my fido boss and for spreading bogus
     XModule releases all around the world.

     Hey boss, have you got a spare 5Gig streamer?

   * Erno Tuomainen for his wonderful Finnish BBS, for his kindness and
     for all the support he gave me.

     Are there any more top-rating modules to leech?

   * Gerardo Iula, for letting me have the source of Tracker (by paying
     :-( ).

     I assumed the money I paid covered the rights of modifying the
     original source and distributing modified versions of your
     program.  Hope you won't worry about it, Gerardo.

   * Sebastiano Vigna & his buddy Reinhard Spisser, for porting GNU
     MakeInfo to the Amiga and for Reinhard's E-Mail technical support.

     Please, continue developing this useful (and hard to learn) tool.
     By the way, MakeInfo crashed my Amiga really bad a couple of times!
     Are my docs that boring?

   * The Amiga, for being the best computer in the world. :^)

     Commodore: Why don't you sell the Amiga project to someone serious
     such as GVP or NewTek?

How to contact the author
*************************

   If you want to make me aware of your suggestions, bug reports, ideas
or you want to send me a gift, a good module or, why not, some money
:-), reach me in any of the following ways:

* Mail
          Bernardo Innocenti
          Via Ventiquattro Maggio, 14
          50129 - Firenze
          ITALY

* FAX
          [phone]
          Attn:  Bernardo Innocenti
          Subj:  Amiga/XModule

* E-Mail
          AmigaNet: Bernardo Innocenti 39:102/201.4
          FidoNet:  Bernardo Innocenti 2:332/118.4
          UseNet:   [e-mail]
          (Glass Globe BBS ++39-577-959054)

   I will try to reply to all my E-Mail, but I'm too lazy to reply
old-style mail.  Your suggestions will be taken into account unless
they are `I want XModule to do ice tea'-style.

Concept Index
*************



 Acknowledgements                       Credits
 Arguments, command line                Getting Started
 Author's address                       Author Info
 Bug reports                            Known Bugs
 Bugs, known ones                       Known Bugs
 Compiling                              Programmers
 Contact the author, how to             Author Info
 Credits                                Credits
 Distribution                           Distribution
 For programmers                        Programmers
 GUI                                    User Interface
 How to contact the author              Author Info
 Known Bugs                             Known Bugs
 Modifying XModule                      Programmers
 Optimization                           Optimization
 Overview of XModule                    Overview
 Panels                                 Panels
 Starting XModule                       Getting Started
 Thanks                                 Credits
 ToolTypes                              Getting Started
 Usage                                  Getting Started
 User Interface                         User Interface
 Windows                                Panels
 XModule overview                       Overview